<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
</head>

<body>
<header>
</header>

<pre><hr>
<b> RELEASE </b>
    * Release 2.1 *

<hr>

<b>NAME</b>
    runCmd, runLinux, runSolaris, runOSF1 - run a computational command on the grid 

<b>SYNOPSIS</b>
    runCmd [options] -c [commandline in quotes] -o [stdout_file] -e [stderr_file] 
    -i [stdin_file] [requirements]

<b>DESCRIPTION</b>

    runCmd is a simple front-end for submitting commands to the TIGR grid.
    runCmd takes a unix command line invocation and distributes it to a free 
    TIGR server machine that satisfies all the requirements given.  runCmd is 
    generally meant to distributed computational programs/scripts like blast and hmm.  
    It is not generally recommended to use to distribute simple shell commands like 
    mkdir, grep or find.  There are options to set requirements on operating system(-s), 
    minimum physical memory(--memory), and machine name(--machines).  

    runCmd's errors are sent to standard error but all error reporting 
    for the given command is sent to .command.stderr.(process) or to a file given with 
    the -e option. By default the runCmd waits for the command to finish before 
    returning (see --nowait).

<b>*** IMPORTANT NOTES PLEASE READ ***</b>
    1. The commandline parameter should always be in double or single quotes 
    to prevent confusion between options to runCmd and options to the actual 
    command to run. See -c option below.  
    
    2. The command and all file parameters need to be located on an NFS server such as
    /usr/local/scratch and /usr/local/projects.  This is because the command will 
    eventually run on a remote machine that will not have access to local files.  

    3. Shell constructs such as pipes("|") and redirects("&gt;") are not supported in the 
    commandline given.  You must use the -o and -e options, see below.

<b>STOPPING A COMMAND</b>
 
    If the -nowait wasn't used then a command can be stopped with a Control-C or
    by sending the process a HUP or TERM signal. runCmd will catch the signal and 
    notify the cluster to terminate the command and then exit.
  
    If the -nowait was used or if the runCmd process is gone then you can use
    the stopCmd command(see http://intranet/~condor/stopCmd.html). 
    

<b>EXAMPLES</b>

    To run blast on a Solaris machine and not wait for the command:
    &gt; cd /usr/local/scratch/dsommer  (an nfs mounted directory)
    &gt; runLinux -c "blastp /usr/local/db/panda/nraa/nraa test.pep -filter none -cpus 1" \
        -o blastp.results -e blastp.errors --nowait

    To run hmmsearch on a Linux machine with atleast 512MB:
    &gt; cd /usr/local/scratch/dsommer  (an nfs mounted directory)
    &gt; runSolaris -c "hmmsearch /usr/local/pfam/hmm.profile test.seq" \
    -o /usr/local/scratch/hmm.results --memory 512

    To run repeatMasker on a OSF1 machine name prowler.tigr.org:
    &gt; runOSF1 -c "repeatMasker /usr/local/scratch/dsommer/multi.fasta.seq" \
    -o /usr/local/projects/dsommer/output --machines prowler.tigr.org
    
    
<b>OPTIONS</b>

    -h, --help
      Print out this manual and exit.

    -c, --commandline [command invocation]
      The command line invocation of a program that would normally be entered 
      at the shell prompt. Must be enclosed in double quotes.  If you 
      command line already contains double quotes use single quotes or escape the
      double quotes in your command line with a \. Example: runLinux "command \"arg\" "

    -o, --output FILE
      The FILE where to redirect standard output of the command. The command will
      be running on a remote machine and so standard output will not be sent
      to the terminal. Defaults to /dev/null meaning stdout will be lost.

    -e, --error FILE
      The FILE where to redirect standard error of the command. The command will
      be running on a remote machine and so standard error will not be sent
      to the terminal. Defaults to runCmd.stderr.(Process) and deleted only if 
      commandline exits with a value of 0. In the case that -e was given standard error
      when not be deleted on success.

    -i, --input FILE
      The FILE where standard input should be read. Defaults to /dev/null.

    --memory MegaBytes
      The minimum amount of memory in megabytes that the destination machine should have.

    --machines
      Comma seperated list of fully qualified hostnames that the command can run on.  
      Currently they must match the operating systems given. 
      Example: --machines prowler.tigr.org

    -s, --system [Linux | Solaris | OSF1]
      Comma seperated list of operating systems the command can run on.  This overrides the
     name of the command invoked. Example: -s Linux,OSF1

    --nowait
      Submit the command and return without waiting for the command to finish. Defaults to off.

    --notify  Notify Script 
      A Script that will be executed when the command is finished.  This script
      MUST be world executable as it will be run as nobody.  This can be used with 
      --nowait on or off.   The scripts output will be sent to /dev/null so any output of
      the script should be sent to a file.  The script will passed the request id, 
      returnValue, message and the email address associated with the request.
        Example: 
           notify.sh -requestID=1608 -returnValue=0 -message="message" -email=user@tigr.org


    -p, --passthrough
      String passed through to the grid. The string is anded(&amp;&amp;) with the rest of the requirements.

    --Evictable<br>      Indicates that this request can be evicted and rescheduled, if needed. The request that is <br>      evictable may run on both desktops and server class machines of the cluster. A non-evictable <br>      request may only run on server class machines of the cluster. By default, a request is<br>      non-evictable.<br><br>    -d, --debug LEVEL
      The level of output produced by runCmd. Each level includes the lower levels.
      Defaults to 2.
      LEVEL      DESCRIPTION
      0          Errors
      1		 Warnings and Errors
      2		 Info, Warnings, and Errors
      3		 Output everything

<b>FILES</b>

    .command.stderr.pid 
       Created if -e option is not set.

    .cid.pid
       File that contains the id assigned to the command by the grid.  
       Needed to stop or track the command.

<b>EXIT CODES</b>
    Passes on the return value of the command that is given.
    On a failure to run the command or improper parameters returns -1.

<b>Dependencies</b>
    TIGR::HTCRequest 

<b>Location of Manual</b>
   http://intranet/~sgeworker/runCmd.html

<b>Author</b>
    Antware Team, antware@tigr.org The Institute for Genomic Research


<hr>


Copyright (c) 2003, The Institute for Genomic Research. All rights reserved.

</pre>

</body>
</html>
